home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 676-700 / 699 / ezasm / ezasm.doc < prev    next >
Text File  |  1995-03-18  |  31KB  |  1,360 lines
  1.  
  2.  
  3.     EZAsm   Version 1.7                  June '92   by Joe Siebenmann
  4.  
  5.  
  6.     DISCLAIMER:
  7.  
  8.     The following only applies to EZAsm, ez.lib, fnm1, fdat1,
  9.     and related .doc files.  ( A68k & Blink have their own
  10.     distribution policies )
  11.  
  12.     You have the right to freely use, copy and distribute this program
  13.     as long as the following conditions are met:
  14.  
  15.     1.    The documentation is included with the program, and neither
  16.         is modified in any way.
  17.  
  18.     2.    The program is not included in any package for profit
  19.         unless written consent from the author is obtained.
  20.         Inclusion in a PD series is OK as long as the charge
  21.         ( for disk, copying etc. ) is REASONABLE.
  22.  
  23.     NOTE: The author does not accept any responsibility for any damage
  24.            that might result from the use of this program.
  25.  
  26.  
  27.  
  28.  
  29.         ---  New for Version 1.7  ---
  30.  
  31.  
  32. o    Support for .fd's.  Now you can directly use all the functions
  33.     in reqtools.library, req.library and others!
  34.  
  35. o    All needed libraries including .fd's and resources
  36.     are opened and closed AUTOMATICALLY!
  37.  
  38. o    Ez.lib updated with new functions.  All arguments are now
  39.     pushed on the stack to avoid register corruption.
  40.  
  41. o    The Exclusive-OR operator "x=" has been replaced with the more
  42.     traditional "^=", and a new "!=" for bit test.
  43.  
  44. o    Support for 68020 and 68030 addressing modes.
  45.  
  46. o    New local, and now GLOBAL optimizations!
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.     EZAsm was written to make programming in 680X0 assembly
  54.     language MUCH easier!  EZAsm combines 680X0 assembly language
  55.     with parts of C.  The result is highly optimized code,    
  56.     with almost HALF the development time!
  57.  
  58.     A68k ( by Charlie Gibbs ) and Blink ( from The Software Distillery )
  59.     are included, and the offsets for all the 2.04 functions are
  60.     internal, so you'll have everything you need to start
  61.     producing executables. ( except the include files )
  62.  
  63.  
  64. Here are some of its advantages:
  65.  
  66.  
  67. o    Your code is converted into the fastest possible
  68.     assembly statement(s), so you automatically write
  69.     "good" code.
  70.  
  71. o    More structured.  Compare and bit test statements can have
  72.     braces and "else" like C.  Being able to use braces lets
  73.     you use assembly language in a whole new way!
  74.  
  75. o    C-like Amiga function calls!  Every 2.04 function in every
  76.     library is supported.
  77.  
  78. o    Your code is much more readable, and easier to debug.
  79.     You can code nearly twice as fast, with fewer syntax errors.    
  80.  
  81. o    No more having to constantly look up which condition code to    
  82.     use for compares, bit tests, or maximum numbers for
  83.     "moveq" or "addq" etc.
  84.  
  85. o    You can freely mix "EZAsm statements" with regular
  86.     assembly statements.
  87.  
  88.  
  89.  
  90.     You need to know a little about assembly language and
  91.     C operators before you dive right in.  If you're new to
  92.     68000 assembly language, I suggest looking at one of the
  93.     many available books on the subject.  The included example
  94.     source programs can give you a good idea about:
  95.  
  96.  
  97. o    General statement syntax.
  98.  
  99. o    Use of "l", "w", "b" size arguments.
  100.  
  101. o    Using assembly statements in your code.
  102.  
  103.  
  104. ****************************************    
  105.  
  106. Using EZAsm:
  107.  
  108.     1.  Create a directory, and copy these files into it:
  109.  
  110.         EZAsm, A68k, Blink, Mk, ez.lib, fnm1, fdat1
  111.  
  112.     2.  CD into your new directory, and you're ready to go!
  113.  
  114.     ( Another good method is to create an ALIAS to load these
  115.     files into VD0: and work from there )
  116.  
  117.  
  118. Mk
  119.  
  120.     Mk is a "make" like program, written in EZAsm, that will
  121.     Execute() the necessary programs for you, creating an
  122.     executable file with a minimum of effort.  It also
  123.     supports an optional include path for A68k, and support
  124.     for a ".mak" file.  The source code is included.
  125.  
  126.     ( WShell users might need to rename Mk )
  127.  
  128.     Usage:
  129.  
  130.         Mk [-iPathToIncludes] [path]file
  131.  
  132.     ( where "file" is your source file with path if needed
  133.     ( No extension ))
  134.  
  135.  
  136.         Execute()'s these commands:
  137.  
  138.         ezasm file.s
  139.         a68k [-iPathToIncludes] file.asm
  140.         blink FROM file.o LIB ez.lib TO file
  141.  
  142. .mak
  143.  
  144.     For times when you need to supply more options for A68k or
  145.     Blink, or invoke other assemblers or linkers, Mk supports
  146.     a .mak file.  Just create a file with the same name as your
  147.     source file, but with a ".mak" extension.  The file should
  148.     contain the EZAsm, A68k, Blink or other commands, with any options
  149.     or switches you need, as if you were entering them from the CLI.
  150.     Any comments should begin with a non-alpha character.
  151.     If Mk finds the .mak file, it will Execute() those commands,
  152.     otherwise it will Execute() the standard commands.
  153.  
  154.  
  155.  
  156.  
  157. ***************************************
  158. *          Addressing Modes           *
  159. ***************************************
  160.  
  161.                     Operand Type
  162.  
  163.      Mode      [A] [B] [C] [D] [E] [F]
  164.  
  165. Dn              *   *   *   -   *   -
  166. An              *   -   *   -   -   -
  167. (An)            *   *   *   *   *   *
  168. (An)+           *   *   *   *   *   *
  169. -(An)           *   *   *   *   *   *
  170. d16(An)         *   *   *   *   *   *
  171. d8(An,Xn)       *   *   *   *   *   *
  172. 16 bit addr     *   *   *   *   *   *
  173. 32 bit addr     *   *   *   *   *   *
  174. d16(PC)         *   -   -   -   *   *
  175. d8(PC,Xn)       *   -   -   -   *   *
  176. immediate       *   -   -   -   *   -
  177.  
  178. bd(An,Xn)       *   *   *   *   *   *     68020/68030
  179. ([bd,An],Xn,od) *   *   *   *   *   *     68020/68030
  180. ([bd,An,Xn],od) *   *   *   *   *   *     68020/68030
  181. bd(PC,Xn)       *   -   -   -   *   *     68020/68030
  182. ([bd,PC],Xn,od) *   -   -   -   *   *     68020/68030
  183. ([bd,PC,Xn],od) *   -   -   -   *   *     68020/68030
  184.  
  185.  
  186.  
  187. declared variables:
  188.  
  189. "foo"  becomes  "foo(a5)"  ( d16(An) )
  190.  
  191. **************************************
  192.  
  193.  
  194. <1-8>    1 - 8
  195. <q>    -128 - 127
  196. <n>    any byte, word, or long size number
  197.  
  198.  
  199. Dn    d0 - d7
  200. An    a0 - a7
  201.  
  202. bd    32 bit displacement
  203. od    32 bit outer displacement
  204.  
  205. Xn      a0 - a7  d0 - d7     Options:          Examples:
  206.                          size:  .w  .l       a2.w  a0.l
  207.                          scale: *1 *2 *4 *8  a1*2  a0.w*4 ( 68020/68030 )
  208.  
  209. {B}    byte data size not allowed for An operands
  210.  
  211.  
  212. **********************************
  213. *       legal        *   legal   *
  214. *      operands      *   sizes   *
  215. **********************************
  216.  
  217.  
  218. Addition  Subtraction
  219.  
  220. ++
  221. --
  222.  
  223.     [C] <op>            L,W,{B}   *
  224.  
  225. +=
  226. -=
  227.     
  228.      Dn <op> [A]        L,W,B           
  229.  
  230.      An <op> [A]        L,W       *
  231.  
  232.     [D] <op> Dn         L,W,B
  233.     
  234.     [B] <op> <n>        L,W,B        
  235.     
  236.     [C] <op> <1-8>      L,W,{B}   *    
  237.  
  238.  
  239. Examples:
  240.  
  241.     Total ++    
  242.     d1 += 10
  243.  
  244. Optional Args:
  245.  
  246.     l, w, b 
  247.  
  248. *    These are now better optimized by making the size word (.w)
  249.     instead of long (.l) for "An" operands.  Its takes 4 less
  250.     cycles, and the upper two bytes are correctly handled!
  251.  
  252. ********************************************
  253.  
  254. Multiplication   Division
  255.  
  256.  
  257. *=
  258.  
  259.     Dn *= [E]           W
  260.  
  261.     Dn *= ##            W   *
  262.  
  263.  
  264. /=
  265.  
  266.     Dn /= [E]           W
  267.     
  268.  
  269. Examples:
  270.  
  271.     d0 *= d1
  272.     d2 /= 2
  273.  
  274. Optional Args:
  275.  
  276.     w,
  277.     s ( signed  divs/muls )
  278.  
  279.  
  280. *    This optimization results in code that's larger then "mulu"
  281.     or "muls", but will execute much faster.  Not all numbers
  282.     can be optimized.  If the number doesn't work, "mulu"
  283.     or "muls" will be used.
  284.  
  285.     ( where ## is a word or byte length number )
  286.  
  287.  
  288. *********************************************
  289.  
  290. And   Or   Exclusive-OR
  291.  
  292.  
  293. &=
  294. |=
  295.  
  296.      Dn <op> [E]        L,W,B
  297.  
  298.     [B] <op> <n>        L,W,B    
  299.     
  300.     [D] <op> Dn         L,W,B
  301.  
  302. ^=
  303.  
  304.     [B] <op> Dn         L,W,B    
  305.     
  306.     [B] <op> <n>        L,W,B
  307.  
  308.  
  309. Examples:
  310.  
  311.     Mask &= %11010000
  312.     Flags |= $f0
  313.  
  314. Optional Args:
  315.  
  316.     l, w, b 
  317.  
  318. *********************************************
  319.  
  320. Shift  Left/Right
  321.  
  322.  
  323. <<
  324. >>
  325.  
  326.      Dn <op> Dn         L,W,B
  327.     
  328.      Dn <op> 1-31       L      *
  329.  
  330.      Dn <op> 1-8        L,W,B
  331.     
  332.     [D] <op> 1          W
  333.  
  334.  
  335. Examples:
  336.  
  337.     d2 << d0
  338.     d1 >> 4
  339.  
  340. Optional Args:
  341.  
  342.     l, w, b,
  343.     a ( arithmetic shift  asl/asr )
  344.  
  345.  
  346. *    Normally you're limited to shifting 1-8, or using a
  347.     data register to hold higher.  This optimized version
  348.     is faster, and saves using a data register!
  349.     ( logical shift only )
  350.  
  351.     
  352. *********************************************
  353.  
  354. Assign
  355.  
  356.  
  357. =    
  358.  
  359.     [B] = [A]           L,W,{B}
  360.     
  361.      An = [A]           L,W
  362.     
  363.  
  364. Examples:
  365.  
  366.     temp = Total
  367.     (a1)+ = 0 w
  368.  
  369. Optional Args:
  370.  
  371.     l, w, b 
  372.  
  373. ********************************************
  374.  
  375. Compare
  376.  
  377.  
  378. >=
  379. <=
  380. !=
  381. >
  382. <
  383. =
  384.  
  385.      Dn <op> [A]        L,W,{B}
  386.     
  387.      An <op> [A]        L,W
  388.     
  389.     [B] <op> <n>        L,W,B
  390.     
  391.   (An)+ <op> (An)+      L,W,B
  392.  
  393.  
  394.  
  395. Syntax types:
  396.  
  397.  
  398.     [opr] <op> [opr] label
  399.  
  400.  
  401.  
  402.     [opr] <op> [opr] {
  403.         .
  404.         .
  405.     }
  406.  
  407.  
  408.  
  409.     [opr] <op> [opr] {
  410.         .
  411.         .
  412.     
  413.     } else {
  414.         .
  415.         .
  416.     }
  417.  
  418.  
  419. Examples:
  420.  
  421.     Total >= 101 Over
  422.  
  423.     Buf != 0 {
  424.         FreeMem( Buf 100 )
  425.     }
  426.  
  427.     (a0)+ = $20 {    
  428.         SPCnt ++
  429.     } else {
  430.         ChrCnt ++
  431.     }
  432.  
  433.  
  434. Optional Args: ( placed AFTER label or brace )
  435.  
  436.     l, w, b,
  437.     s ( signed )
  438.  
  439.  
  440. *********************************************
  441.  
  442. Bit test
  443.  
  444. =
  445. !=
  446.  
  447.  
  448.    Dn:0-31 <op> 0-1     L
  449.     
  450.      Dn:Dn <op> 0-1     L
  451.     
  452.     
  453.    [F]:0-7 <op> 0-1     B    
  454.     
  455.     [F]:Dn <op> 0-1     B
  456.  
  457.  
  458.  
  459. Syntax types:
  460.  
  461.  
  462.     [opr] <op> [opr] label
  463.  
  464.  
  465.  
  466.     [opr] <op> [opr] {
  467.         .
  468.         .
  469.     }
  470.  
  471.  
  472.  
  473.     [opr] <op> [opr] {
  474.         .
  475.         .
  476.     
  477.     } else {
  478.         .
  479.         .
  480.     }
  481.  
  482.  
  483. Examples:
  484.  
  485.     d1:0 != 1 EvenRtn
  486.  
  487.     ($bfe001):6 = 0 LMBDown
  488.  
  489.     d2:d0 = 1 {
  490.         rts
  491.     }
  492.  
  493.  
  494. Optional Args:
  495.  
  496.     ( ignored )
  497.     
  498. Rules:
  499.  
  500. o    No spaces inside first operand.
  501.  
  502. o    Right operand can only be 0 or 1.
  503.  
  504.  
  505. *********************************************
  506.  
  507. Additional Arguments:
  508.  
  509.  
  510. b   forces operation to be byte
  511.  
  512. w     "       "        "   word
  513.  
  514. l     "       "        "   long
  515.  
  516. a    arithmetic shift       ( <<, >> )
  517.  
  518. s    signed                 ( *=, /=, compares )
  519.  
  520. ( it's OK to use multiple arguments ( "w s" etc. ))
  521.  
  522. ( these are RESERVED and can't be used as variables, or labels
  523. ( unless you use upper case ) ) 
  524.  
  525. *********************************************
  526.  
  527. Functions:
  528.  
  529.  
  530. Syntax examples:
  531.  
  532.     CloseWindow( Window )
  533.  
  534.     Buf = AllocMem( 512 #CLEAR_PUBLIC )
  535.  
  536.     Permit( )
  537.  
  538.  
  539.  
  540. Example:
  541.  
  542. --------------------------------
  543.  
  544.  
  545. CLEAR_PUBLIC  equ  $10001
  546. OLDFILE       equ  1005
  547.  
  548.  
  549.  
  550. LONG    FHandle num Rbuf 
  551.  
  552.  
  553.     Rbuf = AllocMem( 100 #CLEAR_PUBLIC )
  554.     beq  Exit
  555.  
  556.     FHandle = Open( "df0:myfile" #OLDFILE )                 
  557.     beq  Exit
  558.  
  559.     d3 = 100    ; preload D3
  560.     num = Read( d0 Rbuf * )
  561.  
  562.         .
  563.         .
  564.         .
  565.  
  566. ---------------------------------
  567.  
  568.  
  569. o    All 2.04 functions are now supported.
  570.     Don't worry, the older 1.3 functions are still there.
  571.     Some 2.04 functions are "for internal use only",
  572.     some "OBSOLETE".  Check "fnm1" for supported functions.
  573.  
  574.     ( AllocWBObject( ), FreeWBObject( ), GetWBObject( ),
  575.     PutWBObject( ) in IconBase, are listed as "OBSOLETE"
  576.     but are still included )
  577.  
  578. Tag Lists:
  579.  
  580.     The "varargs" versions of tag list functions are not
  581.     supported, only the versions that take a pointer to a
  582.     tag list are supported.
  583.  
  584. o    All needed libraries including .fd's and resources
  585.     are opened and closed AUTOMATICALLY, and their bases
  586.     are added to your variables. ( resources don't need to
  587.     be closed )
  588.  
  589.  
  590.  
  591.     All functions within these 2.04 libraries and resources
  592.     are supported:
  593.  
  594.     amigaguide.library        _AmigaGuideBase
  595.     asl.library            _AslBase
  596.     battclock.resource        _BattClockBase
  597.     battmem.resource        _BattMemBase
  598.     ciaa.resource            _CiaABase
  599.     ciab.resource            _CiaBBase
  600.     commodities.library        _CxBase
  601.     disk.resource            _DiskBase
  602.     diskfont.library        _DiskFontBase
  603.     dos.library            _DosBase
  604.     exec.library
  605.     expansion.library        _ExpansionBase
  606.     gadtools.library        _GadToolsBase
  607.     graphics.library        _GfxBase
  608.     icon.library            _IconBase
  609.     iffparse.library        _IFFParseBase
  610.     intuition.library        _IntuitionBase
  611.     keymap.library            _KeymapBase
  612.     layers.library            _LayersBase
  613.     mathffp.library            _MathBase
  614.     mathieeedoubbas.library        _MathIeeeDoubBasBase        
  615.     mathieeedoubtrans.library    _MathIeeeDoubTransBase
  616.     mathieeesingbas.library        _MathIeeeSingBasBase
  617.     mathieeesingtrans.library    _MathIeeeSingTransBase
  618.     mathtrans.library        _MathTransBase
  619.     misc.resource            _MiscBase
  620.     potgo.resource            _PotgoBase
  621.     rexxsyslib.library        _RexxSysBase
  622.     translator.library        _TranslatorBase
  623.     utility.library            _UtilityBase
  624.     workbench.library        _WorkbenchBase
  625.     
  626.  
  627.     All functions for these .devices are supported:
  628.  
  629.     console.device            _ConsoleBase
  630.     input.device            _InputBase    
  631.     ramdrive.device            _RamDriveBase
  632.     timer.device            _TimerBase
  633.  
  634.     You're responsible for calling OpenDevice( ) and
  635.     loading the base to use these .device functions:
  636.  
  637.  
  638. LONG    _TimerBase TimeRequest
  639.  
  640.  
  641.     TimeRequest = AllocMem( 40 #CLEAR_PUBLIC )
  642.     beq    Exit
  643.  
  644.     OpenDevice( "timer.device" 0 TimeRequest 0 )
  645.     bne    Exit
  646.  
  647.     a0 = TimeRequest
  648.     _TimerBase = 20(a0)    ;TimeRequest->tr_node.io_Device
  649.          .
  650.          .
  651.  
  652.  
  653.  
  654. o    The cia.resource functions AbleICR( ), AddICRVector( ),
  655.     RemICRVector( ), and SetICR( ) have been changed to
  656.     simplify the OpenResource( ).  The functions are now
  657.     AbleICRA( ) and AbleICRB( ) etc. and open the corresponding
  658.     ciaa.resource and ciab.resource.
  659.  
  660. o    The leading underscores of the bases are necessary so you can
  661.     use includes without your assembler complaining.  Some library
  662.     bases are already defined in some .i's resulting in
  663.     "multiply defined symbol" errors.
  664.  
  665.  
  666.                    Permit( )
  667.                  AllocMem( 100 #CLEAR_PUBLIC )
  668.                         ^ ^                 ^
  669.                no space | | space           | space
  670.  
  671. o    The function name must be followed immediately with "("
  672.     ( no spaces between ) and then followed by a space or tab.
  673.     If the function has no arguments, it still needs a space in
  674.     the middle.  Arguments must be separated with a space or tab.
  675.  
  676.  
  677.               a2 = ViewAddress( )
  678.               d1 = Read( "myfile" Buf BufLen )
  679.  
  680. o    Address or data registers can be used for returns if
  681.     they're more convenient.  Returns to D0 are now back in.
  682.     Return variables can now be ANY size.  Variables used in
  683.     function arguments must be LONG.
  684.  
  685. o    Several people were concerned when their OpenWindow( ) and
  686.     OpenScreen( ) calls crashed.  The included example source
  687.     "scrwin.s" opens a screen and a window, and is a good
  688.     "base" for starting similar programs.  Problems occur  
  689.     when the NewWindow fields "IDCMPFlags" and "Flags" are
  690.     incorrectly switched, the structure isn't word aligned,
  691.     or fields are the wrong size.
  692.     ( also include any filler "kludge" bytes )
  693.  
  694.  
  695.  
  696. Arguments:
  697.  
  698. o    If your argument is already in a DIFFERENT data or address register,
  699.     you can pass it as an argument directly.  Often a previous function
  700.     will put results in D0, so just pass d0.  If the proper
  701.     register is already loaded, just pass "*".
  702.  
  703.     ( if you pass it the same register it uses, it'll be skipped.
  704.     func defined as:  D0 = Lock( D1 D2 )  "Flock = Lock( d1 -2 )"
  705.     arg "d1" will be skipped ( it's already loaded ))
  706.  
  707. o    You can also use other addressing modes for function arguments
  708.     and returns. ( "(An)", "(An)+", "-(An)", "d16(An)" etc. )
  709.  
  710. o    EZAsm supports argument strings surrounded by double quotes.
  711.     Strings are automatically NULL terminated.
  712.     The following C character constants are supported:
  713.  
  714.  
  715.         \b    backspace
  716.         \f    form feed
  717.         \n    newline
  718.         \r    carriage return
  719.         \t    horizontal tab
  720.         \v    vertical tab
  721.  
  722.  
  723.     Examples:  
  724.  
  725.  
  726.     "Hello, World!\n"
  727.     
  728.     "\t\tHeading\n"
  729.  
  730.  
  731.  
  732.  
  733. NewWin    ds.w    0        ;align
  734.     dc.w    0,0,640,200
  735.     dc.b    -1,-1
  736.     .
  737.     .
  738.  
  739.  
  740. o    To load a pointer to a NewWindow or other "structure" you've
  741.     defined ( above ) use: #NewWin ( etc. ) it'll load its address
  742.     into a data or address register.
  743.  
  744. o    if you need a pointer to one of your declared variables
  745.     ( where the argument goes to an address register ) use:
  746.  
  747.         &foo   ( address of "foo" )
  748.  
  749.     ( output as "lea  foo(a5),An" )
  750.     ( "&" is ONLY recognized inside function arguments )
  751.  
  752. o    Sometimes you have to "play around" with using "#", "&", variables,
  753.     constants etc.  You might be giving it the contents of a variable,
  754.     when it needs its address ( etc. )
  755.   
  756. o    It keeps track of the current library base.  As long as no user
  757.     labels, or close braces are hit, it will skip reloading
  758.     the base register for functions which use the same library base.
  759.  
  760. o    The file "fnm1" contains a list of every function that is
  761.     supported.
  762.  
  763.  
  764. *********************************************
  765.  
  766. Support for .fd's
  767.  
  768.  
  769. Usage:
  770.  
  771. PROTO    [path]LibraryName [path]FDName
  772.  
  773.  
  774. Example:
  775.  
  776. PROTO    req.library req.fd
  777.  
  778.  
  779.     Where PROTO is in upper case, begins at column 1, and
  780.     is placed ABOVE your variable declarations.  The .fd
  781.     file is read, and all its functions, both "##public"
  782.     and "##private", become available for use.  The
  783.     library base is added to your variables, and the
  784.     opening and closing of the library is handled
  785.     automatically.
  786.  
  787.     To avoid any conflicts with other function names, these
  788.     are used first.  Up to 10 .fd's can be used.
  789.  
  790.     "PROTO" can be useful for replacing function argument
  791.     registers, or the offset ( if I happened to get one wrong )
  792.     or to add functions if a new version of a library comes
  793.     out.
  794.  
  795.     Here's an example of a minimal .fd to replace Examine( )
  796.     in _DosBase :
  797.  
  798.  
  799. ##base _DosBase
  800. ##bias 102
  801. Examine()(D1,D2)    ;( arguments within the first "()" are ignored )
  802. ##end
  803.  
  804.  
  805.     ( the default bias is 30 )
  806.  
  807.  
  808. *********************************************
  809.  
  810. Using command line arguments:
  811.  
  812.     Because the automatic opening of libraries will
  813.     corrupt A0 and D0, the following "switches" are provided:
  814.     ( see Mk.s for an example of using "ARGS" )
  815.  
  816. ARGS
  817.  
  818.     A0 is loaded into the variable "Args" ( automatically
  819.     created ) and "clr.b -1(a0,d0.w)" is used to NULL terminate
  820.     the argument string.  The length in D0 is lost.
  821.  
  822. SAVEARGS
  823.  
  824.     A0 and D0 are pushed onto the stack with "movem.l d0/a0,-(sp)". 
  825.     You're responsible for restoring and using them.
  826.  
  827. SAVEREGS
  828.  
  829.     Useful when calling an EZAsm assembly function from your    
  830.     main C code.  Pushes all registers, except D0, onto
  831.     the stack with "movem.l d1-d7/a0-a7,-(sp)" before the "link",
  832.     and restores them with "movem.l (sp)+,d1-d7/a0-a7" right before    
  833.     exiting with "moveq #0,d0", "rts".
  834.  
  835.  
  836. *********************************************
  837.  
  838. Optimizations:
  839.  
  840.     In addition to the many "normal" optimizations performed
  841.     on statements, the following are also performed:
  842.  
  843.  
  844.   STATEMENT          BECOMES       NOTE
  845.  
  846.  
  847.    An = 0          sub.l An,An
  848.  
  849.    [B] = 0         clr [B]          1
  850.  
  851.  
  852.  ( compares )
  853.  
  854.    [B] < 0
  855.    [B] >= 0                         5
  856.  
  857.    [B] = 0
  858.    [B] != 0        tst [B]          6
  859.                    bxx label
  860.  
  861.    ----------------------------------
  862.  
  863.    [B] += <q>
  864.    [B] -= <q>
  865.  
  866.    [B] &= <q>   
  867.    [B] |= <q>
  868.    [B] ^= <q>
  869.  
  870.    [B] = <q>       moveq   <q>,d7   2
  871.                    [opr].l d7,[B]
  872.  
  873.  
  874.    ( compares )
  875.  
  876.    Dn <op> <q>     moveq   <q>,d7   2
  877.                    cmp.l   d7,dn
  878.                    bxx     label
  879.  
  880.    An <op> <q>     moveq   <q>,d7   2
  881.                    cmpa.l  d7,an
  882.                    bxx     label
  883.  
  884.    ----------------------------------
  885.  
  886.    An += <i>       lea  i(An),An
  887.    An -= <i>       lea  -i(An),An   3, 2
  888.  
  889.    An = <n>        lea  n,An        4, 2
  890.  
  891.    
  892.  
  893.  
  894. <i> maximum:  -= 32768   += 32767
  895.  
  896.  
  897. Notes:
  898.  
  899. 1    For byte and word sizes the code size is smaller, for long,
  900.     its smaller and faster. ( then "move #0,[B]" )            
  901.  
  902. 2    Only apply to long sized operations.
  903.  
  904. 3    ( 1-8 handled by "addq", "subq" ( see note in Addition Subtraction ))
  905.  
  906. 4    ( 0 handled by "sub.l An,An" )
  907.  
  908. 5    Taken as signed.
  909.  
  910. 6    In some cases "tst" is eliminated, or D7 is loaded, see below.
  911.  
  912.  
  913.  
  914. New GLOBAL optimizations:
  915.  
  916.  
  917.     Buf != 0 {
  918.         FreeMem( Buf 100 )
  919.     }
  920.  
  921.  
  922.           ( before )                        ( now )
  923.  
  924.     tst.l    Buf(a5)            move.l    Buf(a5),d7
  925.     beq    .l2            beq    .l2    
  926.     movea.l    $4,a6            movea.l    $4,a6    
  927.     movea.l    Buf(a5),a1        movea.l    d7,a1
  928.         .                .
  929.         .                .
  930.  
  931. o    Instead of doing a "tst", the variable is loaded into D7
  932.     ( flags set, and same size and number of cycles ) where it can
  933.     be utilized by a following function call.  In this case it
  934.     loads D7 into A1, saving 2 bytes, and taking only 4 cycles
  935.     instead of 13.
  936.  
  937.  
  938.  
  939.     Fhandle = Open( "df0:myfile" 1005 )    
  940.  
  941.     Fhandle = 0 {
  942.         .
  943.         .
  944.     }
  945.  
  946.  
  947.         .                .
  948.         .                .
  949.     move.l    d0,Fhandle(a5)        move.l    d0,Fhandle(a5)
  950.  
  951.     tst.l    Fhandle(a5)        bne    .l5
  952.     bne    .l5
  953.  
  954.  
  955. o    The flags are set by the "move", so the "tst" instruction
  956.     can be eliminated, saving 4 bytes and 9 cycles.
  957.     ( a label before the "Fhandle = 0 {" statement disables this )
  958.  
  959.  
  960. *********************************************
  961.  
  962. General Info:
  963.  
  964.  
  965. o    Statements can be indented as you like.  Operands, operator,
  966.     and arguments must be separated by at least one space or tab. 
  967.  
  968. o    Braces can be nested up to 30 deep.
  969.     
  970. o    Only one statement per line.
  971.  
  972. o    If you declare variables or use function call's, the first statement
  973.     in your code must be an "EZAsm statement" so it knows when
  974.     to insert the XREF's and/or get stack frame for the
  975.     variables.  Comments, assembly directives, or assembly statements
  976.     placed between your variables and the start of your code will be
  977.     OUT OF PLACE in the output file.
  978.  
  979. o    Comments must begin with "*" or ";" and begin at column 1, or after
  980.     statements ( separated from last argument or operand ) using ";".
  981.     ( both types are transferred to the output file ( some may not ))
  982.  
  983. o    Operands supported:  @141 (octal),  $61 (hex),  %1100001 (binary),
  984.     'a' (ASCII),  97  (decimal).  ASCII strings in operands can
  985.     contain a maximum of 4 characters.
  986.     ( no quotes within quotes permitted )    
  987.  
  988. o    To make labels and symbols as compatible as possible, they arn't
  989.     checked for illegal characters.  Typically the 1st character
  990.     must be a letter, underscore "_", or a period "." .
  991.     The rest of the characters can be any of these plus 0-9.
  992.  
  993. o    Labels and symbols are limited to a length of 127.
  994.     ( Check your assembler to find what length they're
  995.     significant to ( usually around 30 ))
  996.  
  997. o    Labels that don't begin at column 1 must be followed immediately
  998.     with ":".
  999.  
  1000. o    Temporary labels of the form n$, where n consists of decimal
  1001.     digit(s), are supported.  These labels are only in effect till
  1002.     the next non-temporary label is encountered.  ( be careful
  1003.     of "hidden" labels generated by braces )
  1004.  
  1005. o    "moveq #0,d0", "rts" is automatically inserted for you in the
  1006.     closing block of code.
  1007.  
  1008. o    D7 is used as a scratch register for many optimizations, so be
  1009.     careful if you use it.
  1010.  
  1011. o    Labels that it generates for braces are in the range:
  1012.     .l0 to .ln .  This is new, and allows for an unlimited number of
  1013.     labels.  Try to avoid accidentally using them.
  1014.  
  1015. o    Constants generated from argument strings are in the range:
  1016.     .c0 to .cn .  Matching strings are not duplicated.
  1017.   
  1018. o    "SP", "PC", "CCR", "SR" & "USP" ( upper or lower case )
  1019.     are supported, but you must ensure the size etc. is legal.
  1020.  
  1021. o    For best viewing of the output file, set your tabs to 8 spaces.
  1022.     ( printing should be fine )
  1023.  
  1024.  
  1025. IMPORTANT! :
  1026.  
  1027. Use of register A5 is RESERVED!
  1028.  
  1029. ( it contains the base address for variable storage )
  1030.  
  1031.  
  1032. *********************************************
  1033.  
  1034. Variable Declaration:
  1035.  
  1036.  
  1037. LONG    foo Save[10] bar
  1038. WORD    DMASave
  1039. BYTE    Sw
  1040.  
  1041.  
  1042. o    "xxx[n]" reserves n consecutive blocks of given size,
  1043.     with "xxx" pointing to the left-most byte.
  1044.     ( this is for advanced users who need a convenient
  1045.     way to allocate SMALL chunks of memory for saving
  1046.     registers etc. )
  1047.  
  1048. o    You're limited to 14 variables per line.
  1049.  
  1050. o    No other statement types may occur between these lines.
  1051.  
  1052. o    Variables must be separated by at least one space, or tab.
  1053.  
  1054. o    To keep things word aligned, if an odd number of variables are    
  1055.     declared in BYTE, an extra byte will be added.
  1056.     ( this will offset the next "equ" by one )
  1057.  
  1058. o    Declarations must occur JUST BEFORE your program code,
  1059.     and begin at column 1, with LONG, WORD, or BYTE in upper case.
  1060.  
  1061. o    EZAsm uses "link" to allocate space for variables on the stack.
  1062.     The maximum size of this space is 32K.  Since this stack space
  1063.     contains "garbage", code is added to clear it out before use.
  1064.  
  1065.  
  1066. What the stack frame looks like:
  1067.  
  1068.  
  1069. LONG    foo
  1070. WORD    bar Total
  1071. LONG    Cnt
  1072.  
  1073.  
  1074. becomes...
  1075.  
  1076. foo    equ  -4
  1077. bar    equ  -6
  1078. Total  equ  -8
  1079. Cnt    equ  -12
  1080.  
  1081.  
  1082.         h  l           A5   base register
  1083.         i  o           |
  1084.         OOOO OO OO OOOOO    memory bytes
  1085.   (-)   1119 87 65 4321
  1086.         210
  1087.  
  1088.  
  1089.  
  1090. ( Sometimes variables are "adjusted" for proper loading, and
  1091. "-2(a5)" or other displacement may appear in the output file
  1092.  instead of "foo(a5)" or other variable name you might be expecting. )
  1093.  
  1094.  
  1095. *********************************************
  1096.  
  1097. General Info:
  1098.  
  1099.  
  1100. END
  1101.  
  1102.     Data statements ( "dc.b", "ds.l" etc. ) should be
  1103.     placed BELOW the "END" statement.  Any string
  1104.     constants which are generated will also appear
  1105.     below the "END".  Other statements ( "equ",
  1106.     "xref", "xdef" etc. ) can be placed ABOVE your
  1107.     variable declarations, or BELOW "END".
  1108.     ( In the final .asm file "END" will be adjusted )
  1109.  
  1110. o    Instruction size:  In most cases you WON'T NEED
  1111.     A SIZE ARGUMENT.  It knows the size of your variables,
  1112.     address and data registers, and is smart enough to know
  1113.     what size to use.  You'll need to specify a size if
  1114.     the data is smaller than the instruction size you want,
  1115.     ( d1 = $20 w ) or it can't know the size of the operands
  1116.     ( (a2)+ = 3(a0) l ).
  1117.  
  1118.     Caution:  Be aware that if you load small variables into
  1119.           larger ones, the upper bytes arn't cleared and
  1120.           may garbage your result.  Always initialize those
  1121.           variables, or restrict the size of further
  1122.           operations to "b" or "w".
  1123.  
  1124. o    Try not to overuse the size arguments.  Once you get confident
  1125.     it's sizing your instructions correctly ( by checking the
  1126.     .asm file ) you'll find you can eliminate their use almost
  1127.     entirely.  By needlessly restricting a long operation to
  1128.     a word, or byte, you can miss the "quick" optimization.
  1129.  
  1130. o    Since "(a1)" refers to the CONTENTS of the byte, word, or long
  1131.     that A1 points to, "($dff180)" is used in a similar way.
  1132.     ( decimal addr's are also valid: "(14675968)" )
  1133.  
  1134. o    When numbers are used as operands "$fe02" or "37", they are
  1135.     converted to "#$fe02" and "#37".  Operands that it
  1136.     doesn't recognize ( doesn't match with any declared 
  1137.     LONG, WORD, BYTE, or standard "(a1)+" etc. ) get output
  1138.     as is.  This is very useful when you need operands
  1139.     like: "#NewWin", "wd_UserPort(a1)", "$20(a1)", "DMACON(a3)"
  1140.  
  1141. o    Most instructions set condition code flags on the result of the
  1142.     operation.  Often, instead of using a compare to check the
  1143.     result, you can use a branch on condition instruction ( "beq",
  1144.     "bne" etc. ) to jump to a location on the state of a condition
  1145.     code flag.  You need to check which flags are set ( if any )
  1146.     for an instruction.
  1147.  
  1148. o    If at any time you're unsure of what a statement is being
  1149.     output as, or want to check something out, just look
  1150.     at the output file.  Well placed blank lines in your source
  1151.     code can enhance its readability.
  1152.  
  1153. o    I think it's a good idea to get away from using include files.
  1154.     Most assembly source files I see do this.
  1155.     It speeds up the assembler tremendously, and saves
  1156.     endless wear and tear on your drives.
  1157.  
  1158.  
  1159. ****************************************************
  1160.  
  1161. Converting C to EZAsm:
  1162.  
  1163.  
  1164.     Its fairly easy to convert any C code into
  1165.     EZAsm if you follow these guidelines:
  1166.  
  1167.  
  1168.   Allocating structures:
  1169.  
  1170.     Whenever you see "struct VSprite SpriteA" etc.,    
  1171.     you need to either allocate some memory for the
  1172.     structure, or set up your own:
  1173.  
  1174.  
  1175. CLEAR_PUBLIC    equ    $10001
  1176.  
  1177. LONG    SpriteA
  1178.  
  1179.  
  1180.     SpriteA = AllocMem( [structure size] #CLEAR_PUBLIC )
  1181.     beq    Exit
  1182.  
  1183. ---------- or ----------------
  1184.  
  1185. SpriteA    ds.w    0    ;align
  1186.     dc.l    0    ;NextVSprite    
  1187.     dc.l    0    ;PrevVSprite
  1188.     .
  1189.     .
  1190.  
  1191.  
  1192.     ( you could use "#vs_SIZEOF" etc. for [structure size]    
  1193.     and let the assembler get its size from the includes )
  1194.  
  1195.     Some functions will create the structures for you
  1196.     and return a pointer to it ( OpenWindow( ), OpenScreen( )
  1197.     etc. ) just declare a LONG, and load the returned pointer:
  1198.  
  1199. LONG    Window
  1200.  
  1201.     Window = OpenWindow( #NewWindow )
  1202.     beq    Exit
  1203.  
  1204.  
  1205.   Referencing structures:
  1206.  
  1207.     Often you'll need to get at data inside structures.
  1208.     First load the "structure pointer" into an address
  1209.     register, then use the offset of the structure element.
  1210.     Here's a typical example:
  1211.  
  1212.     Move( Window->RPort, 20, 20 );    /* C */
  1213.  
  1214.  
  1215.     a0 = Window
  1216.     Move( wd_RPort(a0) 20 20 )
  1217.  
  1218.     ---- or ----
  1219.  
  1220.     a0 = Window    
  1221.     Move( 50(a0) 20 20 )
  1222.  
  1223.  
  1224.     ( add an include to your source, and the assembler
  1225.     will look-up "wd_RPort" and substitute its offset or,
  1226.     even better, use "50(a0)" instead of "wd_RPort(a0)" )
  1227.  
  1228.     ( it's Ok to use the same address register )
  1229.  
  1230.     a0 = Window
  1231.     a0 = wd_RPort(a0)
  1232.  
  1233.  
  1234.   Loops:
  1235.  
  1236.     I've often thought about trying to add at least a
  1237.     while( ) like statement, but it's just as easy
  1238.     to "code-your-own":
  1239.  
  1240.  
  1241.     for ( foo = 0; foo < 10; foo++ ) {    /* C */
  1242.  
  1243.     }
  1244.  
  1245.  
  1246.  
  1247. LONG    foo
  1248.  
  1249.  
  1250.     foo = 0        ;initialization statements..
  1251.  
  1252. Again:    .        ;body..
  1253.     .
  1254.  
  1255.     foo < 10 {    ;test, and other statements..
  1256.         foo ++
  1257.         jmp Again
  1258.     }
  1259.  
  1260.  
  1261.  
  1262.   Info:
  1263.  
  1264.     If you try converting statements one-for-one in
  1265.     complex C code, you can end up pulling your hair out,
  1266.     and end up with tons of code.  In cases like this,
  1267.     take a step back, and try to figure out the "idea"
  1268.     of what's going on, or what the final result will be,
  1269.     then try to think how you'd code it using EZAsm.
  1270.     I think you'll be surprised by the results!
  1271.  
  1272.  
  1273. *********************************************
  1274.  
  1275. Errors:
  1276.  
  1277.  
  1278. "Illegal argument"
  1279.  
  1280.     The argument found was not valid for the operator.  See
  1281.     the list of "Optional Args" for the operator.  It must
  1282.     be lower case, and be separated from the operands
  1283.     by at least a space or a tab.
  1284.     
  1285. "Illegal operand"
  1286.  
  1287.     One, or both, of the operands are:  not valid for the operator,
  1288.     have an invalid number, or byte size was specified for an
  1289.     "An" operand ( {B} ).  In most cases it's looking for "Dn" or "An"
  1290.     as one of the operands.  ( look under the "legal operands"
  1291.     of the operator for a valid combination )
  1292.  
  1293. "Illegal size"
  1294.  
  1295.     The argument size you specified is not valid for the operator.    
  1296.     Check the "legal sizes" for the operator.
  1297.     
  1298. "Needs size argument"    
  1299.  
  1300.     It doesn't have enough size information about the operands to
  1301.     calculate an instruction size.
  1302.     You need to add an l, w, or b argument.
  1303.  
  1304. "Label not found"
  1305.  
  1306.     No label matching your label argument was found.    
  1307.  
  1308. "Brace mismatch"
  1309.  
  1310.     Checks are made when a closing brace ( "}" ) is hit, and when "END"
  1311.     is hit.  If the brace stack is "messed up" at that time, an error 
  1312.     is given.  If "}" is shown, look from there up.  Both "}" and "END"
  1313.     may appear.  If just "END", look for a "{" or "} else {" without a
  1314.     matching "}".
  1315.  
  1316. "Function not found"
  1317.  
  1318.     No function matching your function name was found.  Check case and    
  1319.     spelling of function name, and be sure there isn't a space before
  1320.     the "(".  Check the list of supported function names in the
  1321.     file "fnm1".
  1322.  
  1323. "Function argument count incorrect"
  1324.  
  1325.     Check the number of arguments you used for the function.  Too many
  1326.     or not enough were used.  With string arguments, check for
  1327.     a missing '"'.  Also look for a missing end ")".
  1328.  
  1329.  
  1330. ( EZAsm doesn't do much checking of normal assembly statements.
  1331. A68k and Blink will catch any problems missed by EZAsm and bring
  1332. them to your attention )
  1333.  
  1334.  
  1335. *******************************************************************
  1336. *******************************************************************
  1337.  
  1338.  
  1339.     Try using EZAsm, I don't think you'll want to go back to
  1340.     "ordinary" assembly language programming. 8^)
  1341.  
  1342.     Why isn't EZAsm shareware?  I don't think you can make much
  1343.     money with shareware, and because I get a lot more satisfaction
  1344.     knowing that people are using it.  I think this is going to be
  1345.     the last version, but if you have any problems, or just want 
  1346.     to say "hello", I'd like hearing from you!
  1347.  
  1348.  
  1349.     Enjoy!
  1350.  
  1351.  
  1352. You can reach me at:
  1353.  
  1354. Joe Siebenmann
  1355. 2204 Pimmit Run Lane  Apt 1
  1356. Falls Church, VA  22043
  1357. ( USA )
  1358.  
  1359. (703) 893-2579
  1360.